global-agent

What is global-agent?

The global-agent npm package is a global HTTP/HTTPS proxy agent that is capable of managing multiple active connections efficiently. It is primarily used to enable proxy support in Node.js applications in a global manner, meaning it can intercept and route outgoing HTTP and HTTPS requests through a specified proxy server. This is particularly useful for applications that need to operate behind corporate proxies or when you want to route traffic for purposes like anonymization.

What are global-agent's main functionalities?

Global HTTP/HTTPS proxy configuration

This code configures a global HTTP proxy for all outgoing HTTP requests. It sets up the proxy server address and specifies hosts for which the proxy should not be used (NO_PROXY). This is useful for applications that need to route their HTTP requests through a proxy server.

require('global-agent/bootstrap');

process.env.GLOBAL_AGENT_HTTP_PROXY = 'http://127.0.0.1:8080';
process.env.GLOBAL_AGENT_NO_PROXY = 'localhost,127.0.0.1';

require('global-agent').createGlobalProxyAgent();

Environment variable configuration

This code demonstrates how to configure both HTTP and HTTPS proxies using environment variables. It allows the application to send all HTTP and HTTPS requests through the specified proxies.

require('global-agent/bootstrap');

process.env.GLOBAL_AGENT_HTTPS_PROXY = 'https://proxy.example.com:443';
process.env.GLOBAL_AGENT_HTTP_PROXY = 'http://proxy.example.com:8080';

Other packages similar to global-agent

proxy-agent

proxy-agent is similar to global-agent as it provides a way to configure HTTP, HTTPS, and other types of proxies for Node.js applications. Unlike global-agent, which primarily focuses on global proxy configuration, proxy-agent allows more granular control over proxy settings on a per-request basis, making it more flexible in scenarios where different requests need different proxy configurations.

http-proxy-agent

http-proxy-agent provides HTTP proxy support specifically for HTTP requests. It is similar to global-agent but is limited to HTTP and does not support HTTPS or other protocols. This makes global-agent a more versatile choice for applications that need support for both HTTP and HTTPS through proxies.

README

global-agent

Global HTTP/HTTPS proxy configurable using environment variables.

• Usage
  • Setup proxy using global-agent/bootstrap
  • Setup proxy using bootstrap routine
  • Runtime configuration
  • Exclude URLs
  • Enable logging
• API
  • createGlobalProxyAgent
  • Environment variables
  • global.GLOBAL_AGENT
• Supported libraries
• FAQ
  • What is the reason global-agent overrides explicitly configured HTTP(S) agent?
  • What is the reason global-agent/bootstrap does not use HTTP_PROXY?
  • What is the difference from global-tunnel and tunnel?

Usage

Setup proxy using global-agent/bootstrap

To configure HTTP proxy:

1. Import global-agent/bootstrap.
2. Export HTTP proxy address as GLOBAL_AGENT_HTTP_PROXY environment variable.

Code:

import 'global-agent/bootstrap';

// or:
// import {bootstrap} from 'global-agent';
// bootstrap();

Bash:

$ export GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:8080

Alternatively, you can preload module using Node.js --require, -r configuration, e.g.

$ export GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:8080
$ node -r 'global-agent/bootstrap' your-script.js

Setup proxy using bootstrap routine

Instead of importing a self-initialising script with side-effects as demonstrated in the setup proxy using global-agent/bootstrap documentation, you can import bootstrap routine and explicitly evaluate the bootstrap logic, e.g.

import {
  bootstrap
} from 'global-agent';

bootstrap();

This is useful if you need to conditionally bootstrap global-agent, e.g.

import {
  bootstrap
} from 'global-agent';
import globalTunnel from 'global-tunnel-ng';

const MAJOR_NODEJS_VERSION = parseInt(process.version.slice(1).split('.')[0], 10);

if (MAJOR_NODEJS_VERSION >= 10) {
  // `global-agent` works with Node.js v10 and above.
  bootstrap();
} else {
  // `global-tunnel-ng` works only with Node.js v10 and below.
  globalTunnel.initialize();
}

Setup proxy using createGlobalProxyAgent

If you do not want to use global.GLOBAL_AGENT variable, then you can use createGlobalProxyAgent to instantiate a controlled instance of global-agent, e.g.

import {
  createGlobalProxyAgent
} from 'global-agent';

const globalProxyAgent = createGlobalProxyAgent();

Unlike bootstrap routine, createGlobalProxyAgent factory does not create global.GLOBAL_AGENT variable and does not guard against multiple initializations of global-agent. The result object of createGlobalProxyAgent is equivalent to global.GLOBAL_AGENT.

Runtime configuration

global-agent/bootstrap script copies process.env.GLOBAL_AGENT_HTTP_PROXY value to global.GLOBAL_AGENT.HTTP_PROXY and continues to use the latter variable.

You can override the global.GLOBAL_AGENT.HTTP_PROXY value at runtime to change proxy behaviour, e.g.

http.get('http://127.0.0.1:8000');

global.GLOBAL_AGENT.HTTP_PROXY = 'http://127.0.0.1:8001';

http.get('http://127.0.0.1:8000');

global.GLOBAL_AGENT.HTTP_PROXY = 'http://127.0.0.1:8002';

The first HTTP request is going to use http://127.0.0.1:8001 proxy and the secord request is going to use http://127.0.0.1:8002.

All global-agent configuration is available under global.GLOBAL_AGENT namespace.

Exclude URLs

The GLOBAL_AGENT_NO_PROXY environment variable specifies a pattern of URLs that should be excluded from proxying. GLOBAL_AGENT_NO_PROXY value is a comma-separated list of domain names. Asterisks can be used as wildcards, e.g.

export GLOBAL_AGENT_NO_PROXY='*.foo.com,baz.com'

says to contact all machines with the 'foo.com' TLD and 'baz.com' domains directly.

Separate proxy for HTTPS

The environment variable GLOBAL_AGENT_HTTPS_PROXY can be set to specify a separate proxy for HTTPS requests. When this variable is not set GLOBAL_AGENT_HTTP_PROXY is used for both HTTP and HTTPS requests.

Enable logging

global-agent is using roarr logger to log HTTP requests and response (HTTP status code and headers), e.g.

{"context":{"program":"global-agent","namespace":"Agent","logLevel":10,"destination":"http://gajus.com","proxy":"http://127.0.0.1:8076"},"message":"proxying request","sequence":1,"time":1556269669663,"version":"1.0.0"}
{"context":{"program":"global-agent","namespace":"Agent","logLevel":10,"headers":{"content-type":"text/plain","content-length":"2","date":"Fri, 26 Apr 2019 12:07:50 GMT","connection":"close"},"requestId":6,"statusCode":200},"message":"proxying response","sequence":2,"time":1557133856955,"version":"1.0.0"}

Export ROARR_LOG=true environment variable to enable log printing to stdout.

Use roarr-cli program to pretty-print the logs.

API

createGlobalProxyAgent

/**
 * @property environmentVariableNamespace Defines namespace of `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables. (Default: `GLOBAL_AGENT_`)
 * @property forceGlobalAgent Forces to use `global-agent` HTTP(S) agent even when request was explicitly constructed with another agent. (Default: `true`)
 * @property socketConnectionTimeout Destroys socket if connection is not established within the timeout. (Default: `60000`)
 */
type ProxyAgentConfigurationInputType = {|
  +environmentVariableNamespace?: string,
  +forceGlobalAgent?: boolean,
  +socketConnectionTimeout?: number,
|};

(configurationInput: ProxyAgentConfigurationInputType) => ProxyAgentConfigurationType;

Environment variables

Name	Description	Default
GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE	Defines namespace of HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables.	GLOBAL_AGENT_
GLOBAL_AGENT_FORCE_GLOBAL_AGENT	Forces to use global-agent HTTP(S) agent even when request was explicitly constructed with another agent.	true
GLOBAL_AGENT_SOCKET_CONNECTION_TIMEOUT	Destroys socket if connection is not established within the timeout.	60000
${NAMESPACE}_HTTP_PROXY	Sets the initial proxy controller HTTP_PROXY value.	N/A
${NAMESPACE}_HTTPS_PROXY	Sets the initial proxy controller HTTPS_PROXY value.	N/A
${NAMESPACE}_NO_PROXY	Sets the initial proxy controller NO_PROXY value.	N/A

global.GLOBAL_AGENT

global.GLOBAL_AGENT is initialized by bootstrap routine.

global.GLOBAL_AGENT has the following properties:

Name	Description	Configurable
HTTP_PROXY	Yes	Sets HTTP proxy to use.
HTTPS_PROXY	Yes	Sets a distinct proxy to use for HTTPS requests.
NO_PROXY	Yes	Specifies a pattern of URLs that should be excluded from proxying. See Exclude URLs.

Supported libraries

global-agent works with all libraries that internally use http.request.

global-agent has been tested to work with:

• got
• axios
• request

FAQ

What is the reason global-agent overrides explicitly configured HTTP(S) agent?

By default, global-agent overrides agent property of any HTTP request, even if agent property was explicitly set when constructing a HTTP request. This behaviour allows to intercept requests of libraries that use a custom instance of an agent per default (e.g. Stripe SDK uses an http(s).globalAgent instance pre-configured with keepAlive: true).

This behaviour can be disabled with GLOBAL_AGENT_FORCE_GLOBAL_AGENT=false environment variable. When disabled, then global-agent will only set agent property when it is not already defined or if agent is an instance of http(s).globalAgent.

What is the reason global-agent/bootstrap does not use HTTP_PROXY?

Some libraries (e.g. request) change their behaviour when HTTP_PROXY environment variable is present. Using a namespaced environment variable prevents conflicting library behaviour.

You can override this behaviour by configuring GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE variable, e.g.

$ export GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE=

Now script initialized using global-agent/bootstrap will use HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables.

What is the difference from global-tunnel and tunnel?

global-tunnel (including global-tunnel-ng and tunnel) are designed to support legacy Node.js versions. They use various workarounds and rely on monkey-patching http.request, http.get, https.request and https.get methods.

In contrast, global-agent supports Node.js v10 and above, and does not implements workarounds for the older Node.js versions.